esp8266 library reference version 1.0.00
Written by Rich Martin (datawiz) August 2020

***********************	
* wifi routines
***********************	

esp.wifi.begin(SSID$,PASS$)
subroutine to connect to wifi network named SSID$ using password PASS$
	- example: esp.wifi.begin("linksys","password")
	- returns: esp.var.return$ will contain the status of the connection:
	- returns: "CONNECT AP" if it connected to the AP but does not have an IP address
	- returns: "CONNECT IP" if it connected to the AP and has an IP address
	- returns: "ERROR" if there was an error from the esp

esp.wifi.ssid()
subroutine to return the name of the current connected SSID
	- example: esp.wifi.ssid
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: esp.var.waitfor.buffer$ will contain the details returned from the esp

esp.wifi.bssid()
subroutine to return the name of the current connected BSSID
	- example: esp.wifi.bssid
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: esp.var.waitfor.buffer$ will contain the details returned from the esp

esp.wifi.encryptiontype(SSID$)
subroutine to return the current encryption settings on the connected Access Point
	- example: esp.wifi.encryptiontype("linksys")
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: esp.var.waitfor.buffer$ will contain the details returned from the esp

esp.wifi.disconnect()
subroutine to disconnect from the currently connected Access Point
	- example: esp.wifi.disconnect
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: esp.var.waitfor.buffer$ will contain the details returned from the esp

esp.wifi.config(IP$, GATEWAY$, NETMASK$)
subroutine to statically configure the IP address, Netmask, and default Gateway for the esp
	- example: esp.wifi.config("192.168.1.100","192.168.1.1","255.255.255.0")
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp

esp.wifi.dns(MODE$,DNS$)
subroutine to configure the DNS settings on the esp
	- example: esp.wifi.dns("OFF","") to remove current DNS setting
	- example: esp.wifi.dns("ON","8.8.8.8") to set the DNS 
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp

esp.wifi.dhcp(MODE$)
subroutine to configure the DHCP mode on the esp
	- example: esp.wifi.dhcp("OFF") to turn off DHCP
	- example: esp.wifi.dhcp("ON") to turn on DHCP
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp

esp.wifi.scannetworks()
subroutine to scan the available wifi networks and return a list of the SSIDs found
	- example: esp.wifi.scannetworks
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: on success, esp.var.waitfor.buffer$ contains the list of networks returned from the esp

esp.wifi.macaddress()
subroutine to return the mac address of the esp
	- esp.wifi.macaddress
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: on success, esp.var.waitfor.buffer$ contains the mac address returned from the esp
		
esp.wifi.restart
subroutine to restart the esp unit (warm boot)
	- example: esp.wifi.restart
	- returns: nothing. pauses 2 seconds to wait for restart to complete
	- notes: if your esp was working fine, then stops for some reason, you may try to restart it then try again.
	- notes: the example file "esprestart.bas" included in this library can be used to restart the esp from the command line

esp.wifi.escape(ATCMD$)
subroutine to send the escape sequence (when esp is in transparent send mode) and immediately run an AT command
	- example: esp.wifi.escape("AT+CIPCLOSE")
	- returns: nothing. Timing is critical for the escape sequence, so no return checking is made on the AT command
	
***********************	
* tcp client routines
***********************	

esp.tcp.client.connect(IP$, PORT$)
subroutine to connect to a server using TCP 
	- example: esp.tcp.client.connect("192.168.1.99","23")
	- example: esp.tcp.client.connect("a80appleiibbs.ddns.net","23")
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- notes: uses transparent send mode on the esp
	
esp.tcp.client.stop()
subroutine to disconnect and existing TCP connection
	- example: esp.tcp.client.stop
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- notes: works if the esp is NOT in transparent send mode. If in transparent send mode, use this instead:
	- notes: esp.wifi.escape("AT+CIPCLOSE")
	
esp.tcp.client.ping(IP$)
subroutine to ping a host by ip or name
	- example: esp.tcp.client.ping("8.8.8.8")
	- example: esp.tcp.client.ping("www.google.com")
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: on success, esp.var.waitfor.buffer$ contains the ping response returned from the esp

esp.tcp.client.write(BYTE$)
subroutine to send a single byte to a connected host
	- example: esp.tcp.client.write("A")
	- returns: nothing.
	- note: may be easier to use the esp.waitfor() subroutine
	
esp.tcp.client.available() as integer
function to return the number of bytes in the input buffer (data received from the connected host)
	- example: bytes_in_buffer% = esp.tcp.client.available()
	- returns: an integer representing the number of bytes in the input buffer. 0 if no bytes in the buffer.
	- note: may be easier to use the esp.waitfor() subroutine
	
esp.tcp.client.read() as integer
function to return a byte from read the input buffer, returns an integer
	- example: byte_value% = esp.tcp.client.read()
	- returns: an integer that is the value of the byte read from the input buffer
	- note: use chr$() to turn the integer into a character that can be printed 
	- note: i.e. byte_value% = esp.tcp.client.read() : print chr$(byte_value%)
	- note: may be easier to use the esp.waitfor() subroutine

esp.tcp.client.print(BYTES$)
subroutine to send a series of bytes to a connected host
	- example: esp.tcp.client.print("Hello World over there!")
	- example: esp.tcp.client.print("YOUR SCORE: "+str$(SCORE%))
	- returns: nothing.
	- note: may be easier to use the esp.waitfor() subroutine
	
esp.tcp.client.println(BYTES$)
subroutine to send a series of bytes to a connected host, appends CR to the string
	- example: esp.tcp.client.print("Hello World over there!")
	- example: esp.tcp.client.print("YOUR SCORE: "+str$(SCORE%))
	- returns: nothing
	- note: appends CRLF to the string if esp.var.crlf% = 1
	- note: may be easier to use the esp.waitfor() subroutine
	
***********************	
* tcp server routines
***********************

esp.tcp.server.begin(PORT$)
subroutine to start up a server on the esp using the provided TCP port, using the existing IP address
	- example: esp.tcp.server.begin("6000")
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	
esp.tcp.server.stop
subroutine to stop the server 
	- example: esp.tcp.server.stop
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp

esp.tcp.server.write(BYTE$)
subroutine to send a byte to the connected host
	- example: esp.tcp.server.write("A")
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp

esp.tcp.server.read()
function to return a byte from the input buffer
	- example: byte_value% = esp.tcp.server.read()
	- returns: an integer that is the value of the byte read from the input buffer
	- note: use chr$() to turn the integer into a character that can be printed 
	- note: i.e. byte_value% = esp.tcp.server.read() : print chr$(byte_value%)
	- note: may be easier to use the esp.waitfor() subroutine

esp.tcp.server.print(CONN%,BYTES$)
subroutine to send a series of bytes to a connected host, host connection specified by CONN%
	- example: esp.tcp.server.print(0,"Hello World over there!") ' sends this string over TCP connection 0
	- example: esp.tcp.server.print(0,"YOUR SCORE: "+str$(SCORE%))
	- returns: nothing.

esp.tcp.server.println(CONN%,BYTES$)
subroutine to send a series of bytes to a connected host, appends CR to the string
	- example: esp.tcp.server.print(0,"Hello World over there!") ' sends this string over TCP connection 0
	- example: esp.tcp.server.print(0,"YOUR SCORE: "+str$(SCORE%))
	- returns: nothing.
	- note: appends CRLF to the string if esp.var.crlf% = 1	

**********************	
* ip routines
***********************	
	
esp.ip.localip
subroutine to return the currently assigned IP address
	- example: esp.ip.localip
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: on success, esp.var.waitfor.buffer$ contains the ip address

esp.ip.netmask
subroutine to return the currently assigned netmask
	- example: esp.ip.netmask
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: on success, esp.var.waitfor.buffer$ contains netmask

esp.ip.gateway
subroutine to return the currently assigned default gatewya
	- example: esp.ip.gateway
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp
	- returns: on success, esp.var.waitfor.buffer$ contains the gateway

***********************	
* low level routines
***********************	
	
esp.waitfor(OUT$,EXPECT$,MODE%,NL%)
subroutine to waitfor data from a remote host using different modes of operation, works in tandem with esp.input.loop()
	OUT$ is a string to send to the connected host, used in MATCH mode
	EXPECT$ is a string used to match against the input from the connected host, used in MATCH mode
	MODE% is an integer value that tells the esp.waitfor routine which mode to operate in, values defined as CONST esp.waitfor.mode.*
	NL% is an integer that tells the esp.waitfor routine to append a NL to the OUT$ when sent to the host, used in MATCH mode
	 if NL% = 1 then a newline is sent, if 0 then no new line is sent
	MATCH mode example: esp.waitfor("SEND","OK",esp.waitfor.mode.match,0)
	- this will send the string "SEND" to the remote host and wait for a response of "OK" from the remote host.
	- if the response is not matched within 10 seconds, the call fails and returns with esp.var.return$ set to the error,
	- otherwise the esp.var.return$ = "" on success
	NORMAL mode example: esp.waitfor("","",esp.waitfor.mode.normal,0)
	- this enables NORMAL mode of esp.input.loop, which just prints every byte received from the connected host. No matching is done.
	- it's easier to just set esp.var.waitfor.mode% = esp.watifor.mode.normal instead
	NUMBER OF BYTES mode example: esp.waitfor("","",100,0) ' return the next 100 bytes received from the remote host
	- this mode will return the number of bytes requested in the MODE%, and should be > 0
	- the bytes returned can be larger than the 256 byte limit of a string, because it uses a longstring to return the data
	- esp.var.waitfor.buffer.big%() will contain the number of bytes you asked for
	- the esp.var.timeout% defines the amount of time to wait for a byte from the host. if this value is exceeded, then 
	- esp.var.return$ is set to an error message, otherwise it will = "" on success
	MUX mode example: esp.waitfor("","",esp.waitfor.mode.mux,0)
	- this mode is used exclusively for TCP SERVER mode of the esp. It ignores the OUT$ and EXPECT$ and is used to receive data from a
	- client connected to the server. The first part of the routine waits for a message from the esp that data is received from a client.
	- because this is a mux mode, multiple clients can be connected, so the routine determines which connection ID is and the length of
	- the payload data that needs to be received. the connection number is saved in esp.var.tcp.server.con% and the number of bytes is
	- stored in esp.var.tcp.server.len%. The payload is saved to longstring esp.var.waitfor.buffer.big%()
	- on success, esp.var.return$ = ""  and on error it will be set to an error message returned from the esp.
	notes: please see example program for details on how these modes are used. You can also use different methods of sending/receiving 
	- data depending on your needs (i.e. esp.tcp.client|server.write|print|println or esp.tcp.client|server.read)

esp.echo.set(MODE$)
subroutine to set the echo mode on the esp. Echo ON cause any data sent to the esp to be sent back to the CMM2
	- example: esp.echo.set("ON")  ' set echo ON
	- example: esp.echo.set("OFF") ' set echo OFF
	- returns: esp.var.return$ = "" if successful, otherwise it will contain the error message returned from the esp

esp.buffer.clear
subroutine to clear the input buffer of any data. data will be lost, so make sure you don't need it before calling this
	- example: esp.buffer.clear
	- returns: nothing.
	- notes: kind of a hack, probably a better way to do this, and not really sure this is needed.
	
esp.input.loop()
subroutine used to receive data from the esp. The esp.waitfor() routine is the primary way to manipulate/modify how the
esp.input.loop() operates, but can be directly manipulated by the esp variables as well. This should be defined in your
initial OPEN COMx line and the interrupt subroutine set to esp.input.loop. See description for esp.waitfor() for more details.
	- example: OPEN COM1:115200,256,esp.input.loop as #5
	- returns: N/A

***********************	
* esp variables
***********************	

const esp.waitfor.mode.mux		= -2
const esp.waitfor.mode.match	= -1
const esp.waitfor.mode.normal	=  0
- modes used in esp.waitfor()

dim esp.var.tcp.server.con% = -1
- as a server, the client connection number

dim esp.var.tcp.server.len% = -1
- as a server, the client send length in bytes

dim esp.var.com.filenum% = 5
- the file number used for the OPEN 

dim esp.var.waitfor.buffer$
- data returned from the esp.waitfor() routine

dim esp.var.waitfor.buffer.big%(2000)
- used in esp.waitfor() to return a large amount of data

dim esp.var.timeout% = 2000
- timeout value in ms, used in many routines that wait for input from a connected host

dim esp.var.return$ = ""
- return value from network sub routines, typically will be "" if successful

dim esp.var.debug% = 0
- debug mode, may print some additional information in send or recv routines. or may not.

dim esp.var.echo% = 1
- determines if the esp.input.loop routine prints data it receives from the esp, 1=on 0=off

dim esp.var.crlf% = 0
- determines if crlf is appended on some routines that send data to a host (see library descriptions for details)

dim esp.var.waitfor.match$ = ""
- the string to match against in the esp.waitfor() routine

dim esp.var.waitfor.mode% = 0
- used to set the response mode for esp.waitfor() routine (normal, match, # of bytes, mux)

dim esp.var.waitfor.done% = 0
- flag to sync the main program to the esp.input.loop during esp.waitfor() in mode match, 0=waitfor loop done, 1=waitfor loop running

dim esp.var.bytecounter% = 0
- number of bytes read from esp.waitfor() routine in modes MUX and NUMBER OF BYTES

In addition to the variables inside the "esp8266var.inc" file, the following 2 variables are also used by the library and need to be defined and set in your own programs:

dim SERVER_IP$  = "192.168.1.100"   ' server ip, hostnames also work
dim SERVER_PORT$= "2662"            ' server port

This defines the IP address and port to connect to in TCP client mode, or defines the port to use in TCP server mode (the SERVER_IP$ isn't used in TCP server mode, as it uses the IP already in use on the esp8266).